<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine manual.	-*-Text-*- -->
<!-- This file documents the TV routines (LMIO;TV >) -->

<!-- It's unclear if these comments mean anything. -->
<!-- It is being modified from LMDOC; TVDOC into LMMAN format. -->
<!-- NOTE: This file is not really up to the standards of the rest of the -->
<!-- manual, in that it is somewhat "internal" in style.  I don't really -->
<!-- want to rewrite it at this time, but eventually we probably should. -->
<!-- [NEW: TV-ALL-PLANES-MASK, NEW MARGIN STUFF, 2 NEW CLEAR FCNS] -->
<!-- Make sure we document reverse video mode. -->
<!-- [Also, must insert TVDEFS and TV2 (when that gets renamed and installed).] -->
<!-- Document the ESCAPE commands from the kbd. -->

<div class='chapter'>4. The TV Display</div><p class='cindent'><!-- tv -->

The principal output device of the Lisp Machine is the TV display
system.  It is used in conjunction with the keyboard as an interactive
terminal, and it can output printed text or graphics.  This chapter
describes the Lisp functions used to manipulate the TV.

<div class='section'>4.1 The Hardware</div>
	The Lisp machine display system is a raster-scan, bit-map
system.  This means that the screen is divided up rectangularly into
points.  The video signal that enters the TV comes from
a memory which has one bit for every point on the screen.
This memory is directly accessible to the program, allowing extremely
flexible graphics.

	The coordinate system normally used has the origin (0,0) at the
top left corner of the screen.  <font class="italic">X</font> increases to the right, and <font class="italic">Y</font>
increases downward.

	There are currently two TV controllers in use.  The 16-bit controller,
which is going away, generates industry-standard composite video, allowing
a screen size of 454. lines from top to bottom with 576. points on each
line.  The newer, 32-bit controller, provides various options.  With the
CPT monitor it generates a black-and-white display of 896. lines with
768. points on each line.  Other monitors can also be supported.

	One thing to be aware of is that the same fonts cannot be used
with both controllers, because the 16-bit controller has its bits reversed.

	It is possible to have a display in which there is more than
one bit per visible point, allowing gray-scale or color.  The set of all
bits which contribute to a single point on the screen is called a
<font class="italic">pixel</font>.  (The point on the screen itself is also sometimes called a
pixel.)  Some of the software operates in terms of pixels.  Pixels are
implemented in an entirely different way in the two controllers.  This
document doesn't really discuss them yet.

	Because of all these options, the Lisp machine system
includes <font class="italic">screen objects</font>.  A screen object contains all the
attributes of a particular TV controller and display monitor.


<div class='section'>4.2 Screens</div><p class='cindent' id='screen'><!-- screen -->

There is a type of Lisp object called a <font class="italic">screen</font>, which is the internal
representation for a physical display with someone looking at it.  Both 
microcode and Lisp functions look at screen objects.
A screen is a structure which contains the following fields:

.ftable 3 500
.item screen-name
An arbitrary character string which appears in the printed representation
of the screen-object.
.item screen-height
The total height of the screen in bits (raster lines, pixels).
.item screen-width
The total width of the screen in bits (pixels).
.item screen-x1, screen-x2, screen-y1, screen-y2
The coordinates of a rectangle which is the portion of the
screen in which allocation of tvobs may occur.  Usually this
is the whole screen, but if there is a who-line it is excluded.
There could be other reserved areas of the screen.
.item screen-plane-mask
0 if this screen is on a 32-bit controller.  If it is on a 16-bit
controller, one of the bits in this mask is on corresponding to
the memory "plane" which contains this screen.  (For instance,
for plane 0 the value of this field would be 1.)  Having more than
one bit on in this mask is not really supported.
.item screen-bits-per-pixel
The number of bits in a pixel.
.item screen-property-list
This is a property list for special features of this screen.
Access this via forms such as <font class="lisp">(get (locf (screen-property-list s)) ':video)</font>
The following property names are standard.
.table 3 500
.item :video
The kind of video this screen uses.
One of <font class="lisp">:black-and-white</font>, <font class="lisp">:gray</font>, <font class="lisp">:color</font>.
.item :controller
The only controller that exists currently is <font class="lisp">:simple</font>.
.item :monitor
The brand-name of the attached monitor, e.g. <font class="lisp">:cpt</font>, <font class="lisp">:barco</font>, etc.
.item :sideways
If the value of this property is non-<font class="lisp">nil</font>,
the monitor is standing on its left side.  The TV routines know how
to draw characters on such a screen, given a rotated font, so that
the text comes out in the normal orientation.
.end_table
.item screen-font-alist
An a-list that associates from font names to font objects.
This is not really used yet.
.item screen-default-font
The font to be used by default on this screen.  
.item screen-buffer
The address in virtual memory of the video buffer for this screen.
.item screen-locations-per-line
The number of locations (containing 16 or 32 bits depending on the controller)
of the video buffer for a scan line.
.item screen-buffer-pixel-array
A two-dimensional array of positive integers, which are pixel values.
The first subscript is the X coordinate and the second subscript is the Y coordinate.
.item screen-buffer-halfword-array
A one-dimensional array of 16-bit words of video buffer.  This is provided to allow
direct manipulation of the video buffer, bypassing the usual microcode primitives.
Note that on a 16-bit controller, the bits in these words are reversed.
.item screen-control-address
The address, suitable for use with <font class="lisp">%xbus-read</font>, of the hardware control registers
for this screen.
.end_table

.defvar tv-default-screen
The value of <font class="lisp">tv-default-screen</font> is the "normal" screen where
text display happens.  Various functions that take a screen as an
optional argument default to this.
.end_defvar


<div class='defun'><font class='exdent'><font class='funcname'>tv-define-screen <font class='italic' color='purple'>name &rest options</font></font></font><br>
Creates and returns a screen whose name is <font class="italic">name</font> (a string)
and whose attributes are controlled by the options.  These attributes
has better correspond to an existing hardware screen.
<font class="italic">options</font> is alternating keywords and arguments to those keywords.  The following
keywords are accepted:
.table 3
<!-- *** Are these defaults still true? *** -->
.item :plane-mask
The value of the <font class="lisp">screen-plane-mask</font> field.  Defaults to 0,
for screens on the 32-bit TV controller.
(This is obsolete.)
.item :height
The value of the <font class="lisp">screen-height</font> field.  Required argument.
.item :width
The value of the <font class="lisp">screen-width</font> field.  Required argument.
.item :x1
The value of the <font class="lisp">screen-x1</font> field.  Defaults to 0.
.item :y1
The value of the <font class="lisp">screen-y1</font> field.  Defaults to 0.
.item :x2
The value of the <font class="lisp">screen-x2</font> field.  Defaults to the width.
.item :y2
The value of the <font class="lisp">screen-y2</font> field.  Defaults to the height,
unless the <font class="lisp">:who-line-p</font> option is specified, in which case
one line of space is left at the bottom of the screen for the who-line.
.item :who-line-p
<font class="lisp">t</font> to leave space for a who-line, <font class="lisp">nil</font> to make the entire
screen available for TVOB allocation.  Defaults to <font class="lisp">t</font>.
.item :buffer
A fixnum which is the address of the video buffer containing
the bits for this screen.  Required argument.
.item :control-address
A fixnum which goes into the <font class="lisp">screen-control-address</font> field.
.item :locations-per-line
The value of the <font class="lisp">screen-locations-per-line</font> field.  Defaults from
the width, the bits per pixel, and the controller type.
.item :bits-per-pixel
The value of the <font class="lisp">screen-bits-per-pixel</font> field.  Defaults to 1.
.item :properties
The value of the <font class="lisp">screen-attributes</font> field.  Defaults to <font class="lisp">nil</font>.
.item :font-alist
The value of the <font class="lisp">screen-font-alist</font> field.  Defaults to <font class="lisp">nil</font>.
.item :default-font
The value of the <font class="lisp">screen-default-font</font> field.  Defaults
according to the type of controller used.
.end_table
</div>

<div class='section'>4.3 Simple Bit Manipulation</div>
	Some arrays of numbers exist which allow access to the TV memory.  These
are regular Lisp arrays and all array operations work on them, but they
are set up so that their data storage is actually in the TV memory.
These arrays are normally found in fields of a screen object.

<font class="lisp">screen-buffer-pixel-array</font> is a two-dimensional array.  Array element
(<font class="italic">x</font>,<font class="italic">y</font>) corresponds to the point whose coordinates are <font class="italic">x</font> and
<font class="italic">y</font>: if the array element is 0, the point is illuminated, and if the
element is 1, the point is dark.  (The opposite is true when the TV is
in reverse-video mode; see below).

The elements of this array are single bits in the usual case, but they can
be small positive numbers in the case of gray-scale or color screens.

In the case of a 16-bit TV, this array accesses whichever
plane is currently selected.

<font class="lisp">screen-buffer-halfword-array</font> is a one-dimensional array of 16-bit
elements, whose exact interpretation depends on the type of TV screen.
Certain programs use this to access the TV buffer memory.

It is possible to do anything to a TV screen, albeit slowly, using the
above two arrays.  However, for efficiency several microcode primitives
are provided which perform certain common operations at much higher speed,
typically close to the maximum speed of the memory.  Most programs use
these microcode primitives or the higher-level functions built on them
rather than accessing the TV buffer memory directly.  The remainder of
this chapter describes these facilities.

<div class='section'>4.4 Fonts</div><p class='cindent'><!-- font -->
	A font is a set of related characters.  It is represented by an array
(of type <font class="lisp">art-1b</font>) which contains the bit patterns used to actually draw the
characters.  The leader of that array contains other required information
such as character widths, height, bookkeeping information, etc.

	There is a microcode entry for drawing characters, which understands the
structure of fonts.  It exists so as to make character drawing as fast
as possible.  User functions do not call the microcode entry directly,
as it is rather kludgey, and handles only the easy cases.  Instead the
TV routines do all the necessary calls.  

	A font usually contains 128 characters.  The widths may be
variable, but the height is always fixed (characters need not actually have
ink all the way from the top to the bottom of the height, but the distance
between lines is fixed for each font).  There are special provisions
for fixed-width fonts to save space and time.  There is a thing called
the baseline, which is a certain vertical position in each character.
For example, the baseline touches the bottom of the legs of a capital A,
and passes through the stem of a lower-case p.
When several fonts are used together, all the baselines are made to line up.

	The way characters are drawn is a little strange (it is done this way for
speed).  There is a thing called a <font class="italic">raster element</font>, which is a row of
1-bits and 0-bits.  A character is drawn by taking a column of raster elements,
(making a rectangle) and OR'ing this into the bit-map memory.  A raster
element can be at most 16 bits wide for hardware reasons, so for large characters
it may take several side-by-side columns to draw the character.  The font
is stored with several raster elements packed into each 32-bit word.  The width
of a raster element is chosen to give maximum packing, and depends on the font.
The reason for the existence of raster elements is to decrease the number
of memory cycles by processing several bits at a time.

	The structure of the array leader of a font is defined by <font class="lisp">defstruct</font>
macros.  Here we list the element names and what they are for.  This structure
is not guaranteed not to be changed in the future, however the macros
are automatically made available to user programs.

.ftable 3
.item font-name
A symbol, in the <font class="lisp">fonts</font> package, whose value is this font.
This symbol also appears in the printed representation.
.item font-char-height
Height of the characters in this font (with a VSP
of 0, this is how far apart the lines would be.)
.item font-char-width
Width of the characters if this is a fixed-width font,
i.e. how far apart successive characters are drawn.
Otherwise contains the width of "space".
.item font-raster-height
Number of raster lines of "ink" in a character (often
the same as <font class="lisp">font-char-height</font>).
.item font-raster-width
Width of a raster element.
.item font-rasters-per-word
Number of elements packed per word (used when accessing the font.)
.item font-words-per-char
Number of words needed to hold one column of elements.
.item font-baseline
Number of raster lines down from the top of the
character cell of the position to align.
.item font-char-width-table
<font class="lisp">nil</font> for fixed width fonts.  Otherwise, contains the
128-long array of character widths.
.item font-left-kern-table
<font class="lisp">nil</font> for non-kerned fonts.  Otherwise, contains the
128-long array of left-kerns.  This is the amount (positive
or negative) to back up the X position before drawing
the character.
.item font-indexing-table
<font class="lisp">nil</font> for narrow fonts which only take one column of
raster elements to draw.  Otherwise, contains a
129-long array which determines what columns of the
font to draw for that character as follows: for
character <font class="italic">i</font>, draw columns <font class="italic">indexingtable</font>(<font class="italic">i</font>) through
<font class="italic">indexingtable</font>(<font class="italic">i</font>+1)-1
inclusive. 
Note that 2 of the above 3 arrays only contain small
positive numbers, so they are usually of type <font class="lisp">art-16b</font> or
<font class="lisp">art-8b</font> to save space.
.item font-next-plane
<font class="lisp">nil</font> usually.  For multi-plane fonts, contains the
font for the next higher plane.  This field is obsolete and no
longer supported.
.item font-blinker-width
Default width for blinkers.
.item font-blinker-height
Default height for blinkers.
.end_table

	The data part of a font array contains an integral number of words per
character (per column in the case of wide characters that need an
indexing table).  Each word contains an integral number of raster 
elements, left adjusted and processed from left to right.  All 32 bits
of each element in this array are used.  For easiest processing by Lisp
programs, it should be of <font class="lisp">art-1b</font> array type. 

	The exact format of the data part of a font array depends on whether
the font is intended to be used with a 16-bit TV controller or a 32-bit controller.
In the 32-bit case, the bits are displayed from right to left.  The maximum
width of a raster element is 32. bits; use of the <font class="lisp">font-indexing-table</font>
is required if characters are wider than this.  If there is more than one
raster element per word, the elements are displayed from right to left.
In the 16-bit case, the bits and raster elements are displayed from
left to right, and the maximum width of a raster element is 16. bits.

<div class='section'>4.5 TVOBs</div>
[Here explain what TVOBs are, how they differ from pieces of paper, what
you use them for, and point to JOBSYS chapter.]  Until this is written,
see <a href='jobsys.html#tvob'>this link</a>.

<div class='section'>4.6 Pieces of Paper</div><p class='cindent' id='pc-ppr'><!-- pc ppr -->
<p class='cindent'><!-- piece of paper -->

	A <font class="italic">piece of paper</font> is something on which you draw
characters.  It is displayed on a certain rectangular portion of a
screen.  It remembers what fonts to use, where to display the next
character, how to arrange margins and spacing, and what to do when
certain special conditions arise.  It optionally displays a blinking cursor
(or several of them).
	All character-drawing in the Lisp
Machine system is accomplished with pieces of paper.  One thing to note
is that pieces of paper do not remember the characters you draw on
them, except by making dots on the TV screen.  This means that if one
piece of paper overlays another, or if the screen is cleared, the
contents of the first is lost.  A higher-level facility (e.g. editor
buffers) must be used if the characters are to be remembered.  The
abbreviation "pc ppr" is often used for "piece of paper". 

	A piece of paper is represented as an ordinary array whose elements are
named by the following accessor macros.  These are automatically available
to the user, but should not normally be used as they are not guaranteed to remain unchanged,
and often contain internal values which are made into more palatable
form by the interface functions.  All screen coordinates in this structure
are absolute screen coordinates; the user interface functions convert these
into coordinates which are relative to the margins of the piece of paper.
.ftable 3
.item pc-ppr-name
An arbitrary string which appears in the printed representation.
.item pc-ppr-screen
The screen-object representing the screen on which this pc ppr displays.
.item pc-ppr-top
The raster line number of the topmost screen line in this pc ppr.
.item pc-ppr-top-margin
The raster line number of the topmost screen line used to draw characters.
The difference between <font class="lisp">pc-ppr-top-margin</font> and <font class="lisp">pc-ppr-top</font> is the size
of the top margin.
.item pc-ppr-bottom
The raster line number of the screen line just below this pc ppr.
.item pc-ppr-bottom-margin
The raster line number of the screen line just below the bottommost point
on which a character can be drawn.  The difference between <font class="lisp">pc-ppr-bottom</font>
and <font class="lisp">pc-ppr-bottom-margin</font> is the size of the bottom margin.
.item pc-ppr-bottom-limit
The lowest raster line to which the cursor may be positioned.  This is a suitable
value to prevent excursion below the bottom margin.
.item pc-ppr-left
The bit number of the leftmost bit in the pc ppr's screen area.
.item pc-ppr-left-margin
The bit number of the leftmost bit used to draw characters.
The difference between <font class="lisp">pc-ppr-left-margin</font> and <font class="lisp">pc-ppr-left</font> is the left margin.
.item pc-ppr-right
The bit number of the bit just to the right of the pc ppr's screen area.
.item pc-ppr-right-margin
The bit number of the bit just to the right of the portion of the pc ppr
in which characters may be drawn.  The difference between <font class="lisp">pc-ppr-right</font>
and <font class="lisp">pc-ppr-right-margin</font> is the right margin.
.item pc-ppr-right-limit
The rightmost bit position to which the cursor may be positioned.  This is
set to a suitable value to prevent excursion past the right margin.
.item pc-ppr-current-x
The X position of the left edge of the next character to be drawn,
i.e. the X coordinate of the cursor position.
.item pc-ppr-current-y
The Y position of the top edge of the next character to be drawn,
i.e. the Y coordinate of the cursor position.
.item pc-ppr-flags
A fixnum containing various bit flags, as follows:
.table 3 0 500
.item pc-ppr-sideways-p
0 normally.  1 if the pc ppr is on a sideways screen, so the X and Y
coordinates should be interchanged before calling the microcode.
.item pc-ppr-exceptions
Non-zero if any special conditions which prevent typeout
are active.  The conditions are:
.table 3 0 500
.item pc-ppr-end-line-flag
1 if <font class="lisp">pc-ppr-current-x</font> is
greater than <font class="lisp">pc-ppr-right-limit</font>.
The default response to this is to advance to the next line.
.item pc-ppr-end-page-flag
1 if <font class="lisp">pc-ppr-current-y</font> is greater than <font class="lisp">pc-ppr-bottom-limit</font>.
The default response to this is to return to the top of the pc ppr.
.item pc-ppr-more-flag
1 if "more-processing" must happen before the next character can
be output.  The default response to this is to display "**MORE**"
and await keyboard input.
.item pc-ppr-output-hold-flag
1 if some higher-level function has decided that output is not to be
allowed on this pc ppr.  For example, its region of the screen might
be in use for something else.  When this is seen a function specified
when the pc ppr was created is called.
.end_table (exceptions)
.end_table (flags)
.item pc-ppr-more-vpos
Y passing here triggers "more processing" by setting <font class="lisp">pc-ppr-more-flag</font>.
Add 100000 to this field to delay until after screen wraparound.
Store <font class="lisp">nil</font> here to inhibit more processing.
.item pc-ppr-baseline
The number of raster lines from the top of the character cell (<font class="lisp">pc-ppr-current-y</font>)
to the baseline.
.item pc-ppr-font-map
An array of fonts.  Normally a font-change command
specifies a code number, which is looked up in this
array to find what font to actually use.  Font 0
is the "principal" font.  The array is usually 26. long.
.item pc-ppr-current-font
The font which is currently selected.
.item pc-ppr-baseline-adj
Y offset for current font to align baseline.  This is the difference between
the <font class="lisp">pc-ppr-baseline</font> and the font's baseline.
.item pc-ppr-line-height
The number of raster lines per character line.
.item pc-ppr-char-width
A character width which is just used for old-style
space/backspace/tab operations and for blinkers.
.item pc-ppr-char-aluf
ALU function for drawing characters.  The default is the value of <font class="lisp">tv-alu-ior</font>.
.item pc-ppr-erase-aluf
ALU function for erasing characters/lines/whole pc ppr.  The default is
the value of <font class="lisp">tv-alu-andca</font>.
.item pc-ppr-blinker-list
(Possibly null) list of blinkers on this pc ppr.
.item pc-ppr-end-line-fcn
Function called when typeout is attempted with <font class="lisp">pc-ppr-end-line-flag</font> set.
The default is to wrap around to the next line.
.item pc-ppr-end-screen-fcn
Function called when typeout is attempted with <font class="lisp">pc-ppr-end-page-flag</font> set.
The default is to wrap around to the top margin.
.item pc-ppr-output-hold-fcn
Function called when typeout is attempted with <font class="lisp">pc-ppr-output-hold-flag</font> set.
The default is to wait for the flag to be cleared by some other process.
.item pc-ppr-more-fcn
Function called when typeout is attempted with <font class="lisp">pc-ppr-more-flag</font> set.
The default is to type **MORE** and await typein.
.end_table (pc ppr)

.subsection "Simple Typeout"

<div class='defun'><font class='exdent'><font class='funcname'>tv-tyo <font class='italic' color='purple'>pc-ppr char</font></font></font><br>
Draws a printing character, or executes a special format character.
The character is drawn at the current cursor position, in the current font,
and the cursor position is shifted to the right by the width of the character.
The following format effectors are recognized:
.table 3 0 500
.item 200
Null.  Nothing happens.
.item 210
Backspace.  The cursor is moved left the width of a space.  At the beginning
of a line it sticks.
.item 211
Tab.  The cursor is moved right to the next multiple of 8 times the width
of a space.
.item 215
Carriage return.  The cursor is advanced to the beginning of the next line,
and that line is erased.  More-processing and screen wrap-around may be
triggered.
.item 240-247
Font change.  The low 3 bits are the font number.
.end_table
Other non-printing characters are displayed as their name enclosed in a box.
These displays are quite wide and currently don't bother to respect the right margin.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-beep </font></font></font><br>
<font class='italic' color='purple'>This function is used to attract the user's attention.
It flashes the screen and beeps the beeper.  Doesn't really have
that much to do with TVs.
</div>

.defvar tv-beep
If the value of <font class="lisp">tv-beep</font> is non-<font class="lisp">nil</font>, the <font class="lisp">tv-beep</font>
function doesn't flash the screen, it only sounds a beep.
The initial value is <font class="lisp">nil</font>.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>si:tv-move-bitpos <font class='italic' color='purple'>pc-ppr delta-x delta-y </font></font></font><br>
Move current X, current Y on piece of paper, keeping inside boundaries.
This function is called from many others.  It is the central place
to keep track of edges, automatic wrap-around, **MORE** processing, etc.
It will set the <font class="lisp">pc-ppr-exceptions</font> flags as necessary.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>si:tv-exception <font class='italic' color='purple'>pc-ppr</font></font></font><br>
This function is called by various TV functions when they encounter
a <font class="lisp">pc-ppr-exceptions</font> flag which they care about (for example, <font class="lisp">tv-crlf</font>
does not care about <font class="lisp">pc-ppr-end-line-flag</font>).
The appropriate function (stored in the pc ppr) is called.  It is up to
that function to correct the condition and clear the exception flag.
</div>

If you want to supply your own exception-handling function for
a piece of paper, you would be well-advised to read the corresponding
system default function first.  They need to do non-obvious things
in some cases.

<div class='defun'><font class='exdent'><font class='funcname'>si:tv-end-line-default <font class='italic' color='purple'>pc-ppr</font></font></font><br>
This is the default end-of-line function, called if an attempt is made
to display a character when the cursor is off the end of a line.
It essentially just does a crlf.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>si:tv-end-screen-default <font class='italic' color='purple'>pc-ppr</font></font></font><br>
This is the default end-of-screen function, called when an attempt is
made to display a character when the cursor is off the bottom of the pc ppr.
It wraps around to the top of the pc ppr.
Note that more-processing is separate from and unrelated to end-of-screen processing.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>si:tv-more-default <font class='italic' color='purple'>pc-ppr</font></font></font><br>
This is the default more processor.  It types out **MORE**,
waits for input, and decides where the next "more" should happen.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-note-input </font></font></font><br>
<font class='italic' color='purple'>The purpose of <font class="lisp">tv-note-input</font> is to prevent "more"s from happening
during normal interactive usage, since typeout is frequently pausing
for user input anyway, and presumably the user is keeping up in his reading.
This function is called by the keyboard handler when a process hangs
waiting for input.  <font class="lisp">tv-note-input</font> arranges (on each active pc ppr)
for a more not to happen until the current
line is reached again; except, if this line is far from the bottom, we prefer
to more at the bottom before wrapping around.  This makes moreing usually happen at the bottom.
</div> 

.subsection "Cursor Motion"

Note that the "cursor" is the x,y position where the top-left corner of the next
character printed will be placed.  (This is not strictly true because there is
base-line adjustment and kerning.)
The cursor doesn't necessarily have a corresponding
blinker; this is under the control of the user program.

Many of these functions are not used by real Lisp Machine code,
but are present for completeness
and to aid compatibility with ITS I/O.  On the other hand, some are heavily used.


<div class='defun'><font class='exdent'><font class='funcname'>tv-home <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Home up to the top-left corner.
Usually you then want to do a <font class="lisp">tv-clear-eol</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-home-down <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Home down the cursor to the bottom-left corner (the beginning of the
last line in the pc ppr).
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-crlf <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Advance to the beginning of the next line, and erase its
previous contents.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-space <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Space forward.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-backspace <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Space backward.  Not too useful with variable-width fonts.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-tab <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Tab.  Spaces forward to the next multiple of 8 times the width of space.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-font <font class='italic' color='purple'>pc-ppr font</font></font></font><br>
This is the common internal routine for changing what font a piece
of paper is to print with.  It does some bookkeeping,
such as adjusting the baseline.  It is OK to set the font to one
which is not in the font map, however this won't change the line-spacing,
which is initially set up according to the tallest font in the font map.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-cursorpos <font class='italic' color='purple'>pc-ppr x y</font></font></font><br>
Sets the "cursor" position of the piece of paper
in raster units (<font class="italic">not</font> character units).  <font class="italic">x</font> and <font class="italic">y</font>
are relative to the margins of the pc ppr.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-read-cursorpos <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Returns two values, the X and Y coordinates of the cursor.
These are relative to the margins of the pc ppr.
</div>

.subsection "Erasing, etc."

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-char <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Clear the current character position.  In a variable-width font,
the width of space is used, which isn't likely to be the right thing.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-eol <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Clear from current position to end of line.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-eof <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Clear from current position to end of piece of paper.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-pc-ppr <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Clear whole piece of paper.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-pc-ppr-except-margins <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Clear all of <font class="italic">pc-ppr</font> except the margins, which are unaffected.
This is useful if the margins contain decorative graphics
'c What Fredkin calls "decorative computer art"
such as outlines.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-clear-screen <font class='italic' color='purple'>&optional screen</font></font></font><br>
Clears the entire screen, and tells the who-line it has been clobbered.
<font class="italic">screen</font> defaults to <font class="lisp">tv-default-screen</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-delete-char <font class='italic' color='purple'>pc-ppr &optional (char-count 1)</font></font></font><br>
Deletes the specified number of character positions immediately to
the right of the cursor, on the current line.  The remainder of
the line slides to the left, and blank space slides in from the
right margin.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-insert-char <font class='italic' color='purple'>pc-ppr &optional (char-count 1)</font></font></font><br>
Inserts the specified number of blank character positions immediately
to the right of the cursor, on the current line.  The remainder of
the line slides to the right, and anything that goes off the right
margin is lost.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-delete-line <font class='italic' color='purple'>pc-ppr &optional (line-count 1)</font></font></font><br>
Deletes the specified number of lines immediately at and below the cursor.
The remaining lines of the piece of paper slide up, and blank spaces
slides in from the bottom margin.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-insert-line <font class='italic' color='purple'>pc-ppr &optional (line-count 1)</font></font></font><br>
Inserts the specified number of blank lines at the cursor.
The remaining lines of the piece of paper slide down, and anything
that goes off the bottom margin is lost.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-black-on-white <font class='italic' color='purple'>&optional screen</font></font></font><br>
Makes the hardware present the screen as black characters on a white background.
(Presently, the <font class="italic">screen</font> argument can also be a plane-mask.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-white-on-black <font class='italic' color='purple'>&optional screen</font></font></font><br>
Makes the hardware present the screen as white characters on a black background.
(Presently, the <font class="italic">screen</font> argument can also be a plane-mask.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-complement-bow-mode <font class='italic' color='purple'>&optional screen</font></font></font><br>
Makes the hardware present the screen in the reverse of its current mode.
(Presently, the <font class="italic">screen</font> argument can also be a plane-mask.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-white-on-black-state <font class='italic' color='purple'>&optional screen</font></font></font><br>
Returns <font class="lisp">:white</font> if the screen is currently presented as white-on-black,
or <font class="lisp">:black</font> if it is currently presented as black-on-white.  The <font class="italic">screen</font>
argument can also be a plane-mask.  If more than one bit is on in the plane-mask,
and not all the planes are in the same state, <font class="lisp">:both</font> is returned.
</div>

.subsection "String Typeout"

<div class='defun'><font class='exdent'><font class='funcname'>tv-string-out <font class='italic' color='purple'>pc-ppr string &optional (start 0) end</font></font></font><br>
Print a string onto a piece of paper.
Optional starting and ending indices may be supplied; if unsupplied,
the whole string is printed.  This is basically just iterated <font class="lisp">tv-tyo</font>,
except in the case of simple fonts it runs much faster by removing
a lot of overhead from the inner loop.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-line-out <font class='italic' color='purple'>pc-ppr string &optional (start 0) end</font></font></font><br>
This variant of <font class="lisp">tv-string-out</font>
is used by the editor's display routines to output one line.
The argument is a string of either 8-bit or 16-bit characters (usually
this is an EINE "line", but the leader is not touched except for the fill pointer.)
The high 8 bits (<font class="lisp">%%ch-font</font>) of each character are the index into the font map
for the font in which that character is to be displayed.  8-bit chars use font 0.
There are optional starting and ending indices; if these are omitted the
whole string is specified.
If during printing the cursor runs off the end of the line, typeout stops
and the index of the next character to be output is returned.  At this point,
the <font class="lisp">pc-ppr-end-line-flag</font> is 1 and the cursor is off the end of the line.
If the whole string is successfully output, <font class="lisp">nil</font> is returned,
and the pc ppr is pointing somewhere in the middle of the line.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-string-length <font class='italic' color='purple'>pc-ppr string &optional (start 0) end stop-x</font></font></font><br>
Compute the display-length of a string, which is the sum of the widths
of the printing characters in it.  Newline characters are ignored.  Tab
characters act as if the string starts at the left margin.  <font class="italic">pc-ppr</font>
is used mainly for its font map.  <font class="italic">start</font> and <font class="italic">end</font> allow you to
process a substring.  <font class="italic">stop-x</font>, if non-<font class="lisp">nil</font>, is a tv-length
at which to stop.  The index in the string of the character after the one
which exceeded the <font class="italic">stop-x</font> is returned as the second value.

The first returned value is the <font class="italic">x</font>-position reached, i.e. the tv-length
of the string.  The second returned value is the next index in the string,
which is <font class="italic">end</font> if <font class="italic">stop-x</font> was not supplied.

Contrast <font class="lisp">tv-compute-motion</font>, which does a
two-dimensional computation taking line-length into account.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-compute-motion <font class='italic' color='purple'>pc-ppr x y string &optional (start 0) end (cr-at-end-p nil)</font></font></font><br>
.defunc (stop-x 0) stop-y
Compute the motion that would be caused by outputting a string.
This is used by the editor to aid in planning its display,
to compute indentations with variable width fonts, to
position the cursor on the current character, etc.
Note that this does not use the "case shift" flavor of font hacking.
Instead, it uses the 16-bit-character flavor that the editor uses.
This means that if you give it an ordinary 8-bit string it will
be assumed to be all in font 0.

The arguments are: the piece of paper, the X and Y position to
start at (<font class="lisp">nil</font>s here use the current position of the pc ppr),
the string, and optionally the starting and ending indices,
a flag saying to fake a crlf at the end of the string, and
two additional arguments which are the
X and Y to stop at; if not given these default to the end of the screen.
Returns 3 values: final-X, final-Y, and an indication of how far down the
string it got.  This is <font class="lisp">nil</font> if the whole string (including the fake
carriage return, if any) was processed without
reaching the stopping point, or the index of the next character to be
processed when the stopping point was reached, or <font class="lisp">t</font> if the stopping point
was reached after the fake carriage return.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-char-width <font class='italic' color='purple'>pc-ppr char</font></font></font><br>
Returns the width of the character, if displayed in the font
current in the pc-ppr.  The width of backspace is negative,
the width of tab depends on the pc ppr's cursor position, and the width
of carriage return is zero.
</div>

.subsection "More Processing"

	More processing is a flow control mechanism for
output to the user.  Lisp machine more processing is similar to more
processing in ITS.  The problem that more processing solves is that 
displayed output tends to appear faster than the user can read it.  The
solution is to stop just before output which has not been read yet is
wiped out, and display "**MORE**".  The user then reads the whole
screen and hits space to allow the machine to continue output.  More
processing normally occurs one line above where the cursor was when the
machine last waited for user input; however, it tries to do an extra
**MORE** at the bottom of the pc ppr, so as to get into a phase where
the **MORE** always appears at the bottom, which is more aesthetic.

.subsection "ALU Functions"

	Some TV operations take an argument called an <font class="italic">ALU Function</font>,
which specifies how data being stored into the TV memory is to be combined with
data already present.  The ALU function is OR'ed directly into a microinstruction,
so specifying a value other than one of those listed below may produce
unexpected disasters.
The following special variables have numeric values
which are useful ALU functions.  

.defvar tv-alu-ior
Inclusive-OR.  Storing a 1 turns on the corresponding bit, otherwise
the bit in TV memory is left unchanged.
.end_defvar

.defvar tv-alu-xor
Exclusive-OR.  Storing a 1 complements the corresponding bit, otherwise
the bit in TV memory is left unchanged.
.end_defvar

.defvar tv-alu-andca
AND-with-complement.  Storing a 1 turns off the corresponding bit, otherwise
the bit in TV memory is left unchanged.
.end_defvar

.defvar tv-alu-seta
Bits are simply stored, replacing the previous contents.
With most functions, this is not useful since it clobbers unrelated
bits in the same word as the bits being operated on.  However,
it is useful for bitblt.
.end_defvar


.subsection "Blinkers"
A <font class="italic">blinker</font> is an attention-getting mark on the screen. 
Often, but not always, it will blink.  The most common type is a
character-sized rectangle which blinks twice a second, but several
other types exist, and it is easy for the user to define new ones. 
Often a piece of paper will have an associated blinker which shows
where the next character will be drawn.  A blinker can be on top of a
character, and the character will still be visible.  This done by
XORing the blinker into the TV memory.  Synchronization between pieces
of paper and blinkers is provided so that when characters are being
drawn on the screen, blinkers are turned off to prevent the picture
from being messed up.  (This is called "opening" a piece of paper, and
should be invisible to the user.)

A blinker is an array, described as follows:
.ftable 3
.item tv-blinker-x-pos
X position of the left edge of the blinker. <font class="lisp">nil</font> if the blinker
should follow the <font class="lisp">tv-blinker-pc-ppr</font>'s current X and Y.
.item tv-blinker-y-pos
Y position of the top edge of the blinker.
.item tv-blinker-pc-ppr
Pc ppr the blinker is associated with.  <font class="lisp">nil</font> for a <font class="italic">roving blinker</font>,
which can go anywhere.
.item tv-blinker-screen
The screen on which the blinker is displayed.
.item tv-blinker-visibility
<font class="lisp">nil</font> invisible, <font class="lisp">t</font> visible, <font class="lisp">blink</font> blinking.
.item tv-blinker-half-period
Time interval in 60ths of a second between changes of the blinker.
.item tv-blinker-phase
<font class="lisp">nil</font> means not visible, anything else means visible in some form.
A complementing blinker has only two phases,
<font class="lisp">nil</font> and <font class="lisp">t</font>, but provision is made for blinkers which go
through an elaborate sequence of states.
.item tv-blinker-time-until-blink
Time interval in 60ths of a second until the next change.  The scheduler
decrements this 60 times a second if the <font class="lisp">tv-blinker-visibility</font> is <font class="lisp">blink</font>.
If it reaches zero, the blinker is blinked.
If this field is <font class="lisp">nil</font>, the blinker is not to be looked at by the scheduler.
.item tv-blinker-function
The function to call to blink the blinker.  The next two fields are for its use.
The arguments to the function are the blinker, an operation code, the
<font class="lisp">tv-blinker-x-pos</font>, and the <font class="lisp">tv-blinker-y-pos</font>.  The operation codes
are <font class="lisp">nil</font> to make the blinker invisible, <font class="lisp">t</font> to make it visible, and
<font class="lisp">blink</font> to blink it.
When this function is called, interrupts have been disallowed and the proper
screen has been selected.
For additional conventions, read the function <font class="lisp">tv-blink</font>.
.item tv-blinker-width
Width in bits of area to complement if
<font class="lisp">tv-rectangular-blinker</font>.
For other blinker types, miscellaneous data.
.item tv-blinker-height
Height in raster lines of area to complement if <font class="lisp">tv-rectangular-blinker</font>.
For other blinker types, miscellaneous data.
.item tv-blinker-sideways-p
<font class="lisp">t</font> =&gt; interchange X and Y before calling microcode.
.end_table

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-blinker-cursorpos <font class='italic' color='purple'>blinker x y</font></font></font><br>
Set the cursor position of a blinker.  If <font class="italic">blinker</font> is a roving
blinker, <font class="italic">x</font> and <font class="italic">y</font> are absolute coordinates.  Otherwise,
they are relative to the margins of <font class="italic">blinker</font>'s piece of paper.
If this blinker was following the pc ppr's cursor, it won't any more.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-read-blinker-cursorpos <font class='italic' color='purple'>blinker </font></font></font><br>
Read the cursor position of a blinker, returning two values, X and Y.
If the blinker is not roving, these are relative to the margins of its
piece of paper.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-blinker-visibility <font class='italic' color='purple'>blinker type</font></font></font><br>
Carefully alters the visibility of a blinker.
<font class="italic">type</font> may be <font class="lisp">nil</font> (off), <font class="lisp">t</font> (on), or <font class="lisp">blink</font>.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-blinker-function <font class='italic' color='purple'>blinker function &optional arg1 arg2</font></font></font><br>
Carefully alters the function which implements a blinker.
<font class="italic">arg1</font> and <font class="italic">arg2</font>, if supplied, change <font class="lisp">tv-blinker-height</font>
and <font class="lisp">tv-blinker-width</font>, which are really just general arguments to the function.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-set-blinker-size <font class='italic' color='purple'>blinker width height</font></font></font><br>
Carefully changes the size of a blinker, consulting the function which
implements it if that function has a <font class="lisp">tv-set-blinker-size-function</font> property.
</div>

<div class='section'>4.7 Graphics</div>
<div class='defun'><font class='exdent'><font class='funcname'>tv-draw-line <font class='italic' color='purple'>x1 y1 x2 y2 alu screen</font></font></font><br>
Draws a straight line between the points (<font class="italic">x1</font>,<font class="italic">y1</font>) and (<font class="italic">x2</font>,<font class="italic">y2</font>),
merging the line into the existing contents of the screen with the specified
alu function.  This is a fast micro-coded function.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>bitblt <font class='italic' color='purple'>alu width height from-array from-x from-y to-array to-x to-y</font></font></font><br>
This function moves a portion of one two-dimensional numeric array into
a portion of another, merging them under the control of a specified alu function.
It has several applications, including shifting portions of the TV screen
around (use the <font class="lisp">screen-buffer-pixel-array</font>), saving and restoring
portions of the TV screen, writing half-tone and stipple patterns into the
TV screen, and general array-moving.

<font class="lisp">bitblt</font> operates on a rectangular region of <font class="italic">to-array</font> which starts at the coordinates
(<font class="italic">to-x</font>,<font class="italic">to-y</font>) and has extent <font class="lisp">(abs <font class="italic">width</font>)</font> in the <font class="italic">X</font>
direction and <font class="lisp">(abs <font class="italic">height</font>)</font> in the <font class="italic">Y</font> direction.  An error occurs
if this region does not fit within the bounds of <font class="italic">to-array</font>.  Note that the
coordinates and the <font class="italic">height</font> and <font class="italic">width</font> are in terms of array elements,
not bits, although the actual operation is done bitwise.  <font class="italic">from-array</font> needn't
be as big as the specified region; conceptually, <font class="lisp">bitblt</font> replicates
<font class="italic">from-array</font> a sufficiently-large number of times in both <font class="italic">X</font> and <font class="italic">Y</font>,
then picks out a rectangular region containing the same number of bits
as the destination region, starting at the coordinates (<font class="italic">from-x</font>,<font class="italic">from-y</font>).
<font class="lisp">bitblt</font> combines these two regions
under control of <font class="italic">alu</font>.  The "A" operand is the <font class="italic">from-array</font>, thus
an alu function of <font class="lisp">tv-alu-seta</font> copies the <font class="italic">from-array</font>, ignoring the
previous contents of the selected region of the <font class="italic">to-array</font>.

The specified <font class="italic">X</font> and <font class="italic">Y</font> coordinates are always the upper-left corner
(minimum coordinate values) of the selected region.

<font class="lisp">bitblt</font> normally works in a left-to-right and top-to-bottom order, that
is with increasing coordinate values.  When using overlapping <font class="italic">from</font> and
<font class="italic">to</font> arrays, for instance when shifting a portion of the TV screen slightly,
it may be necessary to work in one of the other three possible orders.
This is done using the sign of the <font class="italic">width</font> and <font class="italic">height</font> arguments.
If <font class="italic">width</font> is negative, decreasing <font class="italic">X</font> coordinates are used, and
if <font class="italic">height</font> is negative, decreasing <font class="italic">Y</font> coordinates are used.

For the sake of efficiency, <font class="lisp">bitblt</font> requires that the <font class="italic">from-array</font>
and <font class="italic">to-array</font> have word-aligned rows.  This means that the
first dimension of these arrays must be a multiple of 32. divided by the
number of bits per array-element.  All TV screen arrays are forced by
hardware to satisfy this criterion anyway.
</div> 

<div class='section'>4.8 The Who Line</div>	The <font class="italic">who line</font> is a line at the bottom of the screen which
contains information on what the program is currently doing.  The who
line has its own pc ppr and is updated whenever the software goes into
an I/O wait.  In addition, there are two short line segments (called <font class="italic">run lights</font>) at
the bottom of the screen which are controlled by the microcode and by the scheduler.  The
one on the right lights up when the machine is running (not waiting and
not paging), and the one on the left lights up when the disk is running
(paging).

<div class='defun'><font class='exdent'><font class='funcname'>tv-who-line-update <font class='italic' color='purple'>&optional state</font></font></font><br>
This function updates all fields of the who-line which have changed.  It is called
from various functions which change the "state of the machine" as perceived by
the user.  The optional argument, <font class="italic">state</font>, is a string to be displayed
in the state field.
If <font class="italic">state</font> is not specified, the value of <font class="lisp">tv-who-line-run-state</font> is used, which is
usually <font class="lisp">"RUN"</font>.
</div>

.defvar tv-who-line-list
The value of <font class="lisp">tv-who-line-list</font> is a list of who-line fields.  Each field
is a list; the first four elements of the list constitute a structure
containing the following components:
.ftable 3
.item tv-who-line-item-function
A function to call, given the field as its argument.  The function is supposed
to update the field of the who-line if it has changed.  The list elements of the field
after the first four are for the use of this function.
.item tv-who-line-item-state
If <font class="lisp">nil</font>, the who-line has been clobbered (e.g. by clearing of the screen)
and the field must be updated.  Otherwise, this is used by the function in
an unspecified way to remember its previous state.
.item tv-who-line-item-left
The bit position of the left edge of the portion of the who-line containing this field.
.item tv-who-line-item-right
The bit position (+1) of the right edge of the portion of the who-line containing this field.
.end_table

The initial <font class="lisp">tv-who-line-list</font> is set up to display the time, the name
of the person logged-on to the machine, the current package, the "state"
of a certain selected process, and name and position of the current input file.
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>tv-who-line-prepare-field <font class='italic' color='purple'>field</font></font></font><br>
This is called by <font class="lisp">tv-who-line-item-function</font>s in preparation for redisplay
of a who-line field.  The portion of the screen on which the field displays
is erased and the <font class="lisp">tv-who-line-pc-ppr</font>'s cursor is set to the beginning of
the field.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-who-line-string <font class='italic' color='purple'>field</font></font></font><br>
This is a useful function to put into a who-line field.  It displays the
string which is the value of the symbol which is the fifth element of the field,
if it is not <font class="lisp">eq</font> to the string previously displayed.
</div>

.defvar tv-who-line-pc-ppr
The value of <font class="lisp">tv-who-line-pc-ppr</font> is a piece of paper which 
is used to display the characters in the who-line.
.end_defvar

.defvar tv-who-line-stream
The value of <font class="lisp">tv-who-line-stream</font> is a stream whose output
displays on the <font class="lisp">tv-who-line-pc-ppr</font>.
.end_defvar

.defvar tv-who-line-process
The value of <font class="lisp">tv-who-line-process</font> is the process whose state is to
be displayed in the who-line.  <font class="lisp">process-wait</font> calls <font class="lisp">tv-who-line-update</font>
if this is the current process.
<font class="lisp">tv-who-line-process</font> is normally the main process of the job
which owns the keyboard.
.end_defvar

.defvar tv-who-line-run-state
Normally the string "RUN".  This is what appears in the wholine
when the machine isn't waiting for anything.
.end_defvar

.defvar tv-who-line-run-light-loc
Unibus address of the TV memory location used for the run-light.
.end_defvar

.defvar tv-who-line-state
This is a special variable which exists inside of <font class="lisp">tv-who-line-update</font>.
.end_defvar

<div class='section'>4.9 Microcode Routines</div>
<div class='defun'><font class='exdent'><font class='funcname'>tv-select-screen <font class='italic' color='purple'>screen</font></font></font><br>
This microcode primitive selects a screen for use by the <font class="lisp">tv-draw-char</font>
and <font class="lisp">tv-erase</font> functions.  It sets up microcode variables and hardware
registers.  Note that this state is not preserved through process switching,
so this primitive should only be called with <font class="lisp">inhibit-scheduling-flag</font>
bound to <font class="lisp">t</font>, which is normally desired for other reasons anyway.

<font class="lisp">tv-select-screen</font> should also be used before referencing the TV arrays,
such as the <font class="lisp">screen-buffer-pixel-array</font>, if a 16-bit TV controller is being used.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-draw-char <font class='italic' color='purple'>font-array char-code x-bit-pos y-bit-pos alu-func</font></font></font><br>
The <font class="italic">x-bit-pos</font> and <font class="italic">y-bit-pos</font> are of the top left corner of the character.
(0,0) is the top left corner of the screen.
<font class="lisp">tv-draw-char</font> extracts the raster elements for one character
(or one column of a wide character) and displays them at the indicated
address in the currently-selected plane,
using the indicated ALU function to combine them with the bits
already there.  Note that this function does not know anything about
pieces of paper; no pc ppr handling is in microcode.
<!-- [More to be said about conventions.] -->
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-erase <font class='italic' color='purple'>width height x-bit-pos y-bit-pos alu-func</font></font></font><br>
This function is in microcode.
<font class="italic">width</font> and <font class="italic">height</font> are in bits, and should be fixnums.
A rectangle of the indicated
size, of all 1s, is created and merged into the rectangle of TV memory
in the currently-selected plane
whose top left corner is at (<font class="italic">x-bit-pos</font>,<font class="italic">y-bit-pos</font>),
using the specified <font class="italic">alu-func</font>.  Usually
the ANDCA function is used for erasing, but XOR is used
for the blinking cursor etc.  Note that <font class="italic">width</font> and <font class="italic">height</font>
must be greater than zero.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-draw-line <font class='italic' color='purple'>x0 y0 x1 y1 alu-func screen</font></font></font><br>
This function is in microcode.
A straight line is drawn from the point (<font class="italic">x0,y0</font>)
to the point (<font class="italic">x1,y1</font>).  These points had better not
lie outside the screen.  The bits that form the line are
merged into the screen with the specified alu function.
<font class="lisp">tv-select-screen</font> is applied to <font class="italic">screen</font> before
the line is drawn.
</div>

<div class='section'>4.10 Opening a Piece of Paper</div>
	Before a piece of paper can be manipulated, any blinkers
which may intercept it must be turned off (i.e. their <font class="lisp">tv-blinker-phase</font>
must be <font class="lisp">nil</font>).  The operation of assuring this is called <font class="italic">opening</font>
the piece of paper.  Similarly, before a blinker's location, size, shape,
visibility, or other attributes can be changed, it must be opened, that
is made to have no visible effect on the screen.
	Once a blinker has been opened, we must make sure that the clock
function, which implements the blinking, does not come in and turn the
blinker back on.  This is done in the simplest possible fashion, by
binding the <font class="lisp">inhibit-scheduling-flag</font> non-<font class="lisp">nil</font>, which causes
the microcode not to switch to another process.  [In the present system
processes are never interrupted, not even by the clock, and this variable is ignored.]
This also prevents any other process from coming in and messing up the
piece of paper by trying to type on it at the same time.
	Once we are done with a blinker or piece of paper, and don't
need to have it opened any more, we want the blinkers to reappear.
It looks best if a blinker reappears right away, rather than at the next
time it would have blinked.  However, for efficiency we don't want to
disappear and reappear the blinker every time a TV operation is performed.
Rather, if a program is doing several TV operations right in a row,
the first one will turn off the blinkers, the succeeding ones will
notice that the blinkers are already off, and then soon after the sequence
is completed the blinker will come back on.  This is implemented by having
the next clock interrupt after we get out of the TV code turn the blinker on.

<div class='defmac'><font class='exdent'><font class='funcname' id='tv-prepare-pc-ppr'>tv-prepare-pc-ppr</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><br>The form <font class="lisp">(tv-prepare-pc-ppr (<font class="italic">pc-ppr</font>) <font class="italic">form1 form2 ...</font>)</font>
opens the piece of paper which is the value of the variable <font class="italic">pc-ppr</font>
and evaluates the forms with it open.  This macro contains all the knowledge
of how to open a pc ppr, including disabling interrupts, finding and
opening the blinkers, and selecting the proper screen.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-open-blinker <font class='italic' color='purple'>blinker</font></font></font><br>
The specified blinker is temporarily turned off; the next clock interrupt
when <font class="lisp">inhibit-scheduling-flag</font> is <font class="lisp">nil</font> will turn it back on.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-open-screen
Opens <font class='italic' color='purple'>all the visible blinkers, preparatory to arbitrary</font></font></font><br>
munging of the screen, for instance picture drawing.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-blink <font class='italic' color='purple'>blinker type </font></font></font><br>
The function to blink a blinker.
<font class="italic">type</font> is one of the symbols <font class="lisp">nil</font> (off), <font class="lisp">t</font> (on), or <font class="lisp">blink</font>.
<font class="lisp">tv-blink</font> checks <font class="italic">type</font>, selects the proper screen, digs up the
blinker position out of the pc ppr if necessary, and calls the blinker's function
to do the actual display.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-rectangular-blinker <font class='italic' color='purple'>blinker type x y</font></font></font><br>
A <font class="lisp">tv-blinker-function</font> function for rectangular blinkers (the default).
Ignores <font class="italic">type</font>, just complements.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-hollow-rectangular-blinker <font class='italic' color='purple'>blinker type x y</font></font></font><br>
Function for hollow rectangles.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-character-blinker <font class='italic' color='purple'>blinker type x y</font></font></font><br>
Function for blinkers defined by a character.  Arg1 ("height")
is the font, and arg2 ("width") is the character in the font.
The character is XORed in and out as the blinker blinks.
</div>

<div class='section'>4.11 Creating Pieces of Paper and Blinkers</div>
<div class='defun'><font class='exdent'><font class='funcname'>tv-define-pc-ppr <font class='italic' color='purple'>name font-map &rest options</font></font></font><br>
This function creates a returns a piece of paper.  Keyword arguments
allow the user to specify some of the many attributes of the piece of
paper and leave the remainder to default.
<font class="italic">name</font> is just a string which is remembered in the pc-ppr and appears
in its printed representation.  <font class="italic">font-map</font> may be either a list or an array of fonts;
or it may be <font class="lisp">nil</font>, which causes the font map to be taken from the screen's default.
The remaining arguments are alternating keywords (which should
be quoted) and values for those keywords.  For example,
<pre class="lisp">
(setq foo (tv-define-pc-ppr "foo" (list fonts:tvfont)
			    ':top 300
			    ':bottom 400))
</pre>

Valid option keywords are:

.table 3
.item :screen
The screen on which the piece of paper is to display.
The default is <font class="lisp">tv-default-screen</font>.
.item :top
Raster line number of highest line in the pc ppr.
Defaults to <font class="lisp">screen-y1</font> of the specified screen, the top.
.item :bottom
Raster line number + 1 of lowest line in the pc ppr.
Defaults to <font class="lisp">screen-y2</font> of the specified screen,
just above the who line (if there is one) at the bottom
of the screen.
.item :left
Raster point number of left edge of pc ppr.
Defaults to <font class="lisp">screen-x1</font> of the specified screen, the left edge.
.item :right
Raster point number + 1 of right edge of the pc ppr.
Defaults to <font class="lisp">screen-x2</font> of the specified screen, the right edge.
.item :blinker-p
<font class="lisp">t</font> if this pc ppr should have a blinker on its cursor,
<font class="lisp">nil</font> if the cursor should be invisible.
Default is <font class="lisp">t</font>.
.item :activate-p
<font class="lisp">t</font> if this pc ppr should be initially active.
Active means that its blinkers can blink.
The default is <font class="lisp">t</font>.
.item :reverse-video-p
<font class="lisp">t</font> if this pc ppr should be in the inverse of the
normal black-on-white mode.  This works by changing <font class="lisp">pc-ppr-char-aluf</font>
and <font class="lisp">pc-ppr-erase-aluf</font>.
Default is <font class="lisp">nil</font>.
.item :more-p
<font class="lisp">t</font> if this pc ppr should have more processing.
Default is <font class="lisp">t</font>.
.item :vsp
Number of raster lines between character lines.
This is added to the maximum height of the fonts in
the font map to get the height of a line in this
pc ppr.  The default is 2.
.item :left-margin
Amount of unused space at the left edge of the pc ppr.
The default is 0.
.item :top-margin
Amount of unused space at the top.  The default is 0.
.item :right-margin
Amount of unused space at the right.  The default is 0.
.item :bottom-margin
Amount of unused space at the bottom.  The default is 0.
.item :end-line-fcn
A function which is invoked when typeout reaches the
end of a line.  The default is one which wraps around
to the next line.
.item :end-screen-fcn
A function which is invoked when typeout reaches
the bottom of the pc ppr.  The default is one which
wraps around to the top.
.item :output-hold-fcn
A function which is invoked when typeout encounters
the output-hold flag.  The default is one which waits
for some other process to clear the flag.
.item :more-fcn
A function which is invoked when more processing
is necessary.  The default is one which types
**MORE** and waits for the user to hit a character,
then ignores that character and continues typing.
.item :blink-fcn
The function to implement the blinker if <font class="lisp">:blinker-p</font>
is not turned off.  The default is <font class="lisp">tv-rectangular-blinker</font>.
.item :sideways-p
<font class="lisp">t</font> means the monitor is standing on its left side
instead of its bottom; change things around
appropriately.  The default comes from the specified screen.
.item :integral-p
<font class="lisp">t</font> means that the piece of paper should be forced
to be an integral number of lines high; it will be
made slightly smaller than the specified size if
necessary.  The default is <font class="lisp">nil</font>.
.item :font-map
Set the font-map.  This is intended to replace the passing
in of the font-map as the second argument.
.end_table
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-define-blinker <font class='italic' color='purple'>pc-ppr &rest options</font></font></font><br>
Define a blinker on a piece of paper.  The options are similar
in syntax to those in <font class="lisp">tv-define-pc-ppr</font>.  Valid options are:
.table 3
.item :height
Number of raster lines high.  The default comes
from the first font in the pc ppr's font map.
.item :width
Number of raster points wide.  The default comes
from the first font in the pc ppr's font map.
.item :function
The function to implement the blinker.  The default
is <font class="lisp">tv-rectangular-blinker</font>.
.item :arg1
Another name for <font class="lisp">:width</font>.  Use this with <font class="lisp">:function</font>s
which don't interpret their first "argument" as a width.
.item :arg2
Another name for <font class="lisp">:height</font>.  Use this with <font class="lisp">:function</font>s
which don't interpret their second "argument" as a height.
.item :visibility
Initial visibility, <font class="lisp">t</font>, <font class="lisp">nil</font>, or <font class="lisp">blink</font>.
Default is <font class="lisp">blink</font>.
.item :follow-p
<font class="lisp">t</font> if this blinker should follow that pc ppr's cursor.
Default is <font class="lisp">nil</font>.
.item :roving-p
<font class="lisp">t</font> if this blinker is not confined to a single piece
of paper.  In this case the pc ppr argument is ignored and should be <font class="lisp">nil</font>.
Default is <font class="lisp">nil</font>.
.item :activate-p
<font class="lisp">t</font> if this blinker should be initially active.
The default is <font class="lisp">nil</font>.
.item :half-period
Number of 60ths of a second between changes in the blinker.
Default is 15.
.item :screen
The screen on which the blinker should appear.  The default
is to take it from the pc ppr, or from <font class="lisp">tv-default-screen</font>
in the case of a roving blinker.
.item :sideways-p
<font class="lisp">t</font> to make the blinker be rotated 90 degrees.  Default
is to take it from the pc ppr.
.end_table
You may give <font class="lisp">nil</font> as a pc-ppr, in which case you must specify
<font class="lisp">:width</font> and <font class="lisp">:height</font> (or <font class="lisp">:arg1</font> and <font class="lisp">:arg2</font>) since they will
default to <font class="lisp">nil</font>.
You should give <font class="lisp">nil</font> as pc-ppr if and only if you specify <font class="lisp">:roving-p</font>,
probably, since <font class="lisp">:roving-p</font> means this blinker is not on a pc ppr.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-redefine-pc-ppr <font class='italic' color='purple'>pc-ppr &rest &eval options</font></font></font><br>
Redefine some of the parameters of a pc ppr.
The allowed options are <font class="lisp">:top</font>, <font class="lisp">:bottom</font>, <font class="lisp">:left</font>, <font class="lisp">:right</font>,
<font class="lisp">:top-margin</font>,
<font class="lisp">:bottom-margin</font>, <font class="lisp">:left-margin</font>, <font class="lisp">:right-margin</font>, <font class="lisp">:vsp</font>, <font class="lisp">:integral-p</font>,
<font class="lisp">:more-p</font>, <font class="lisp">:screen</font>,
and <font class="lisp">:fonts</font>.  <font class="lisp">:fonts</font> allows you to change the font map,
which can change the line height.  The size of the blinker
will not be changed, but perhaps it should be.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-deactivate-pc-ppr <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Cause a piece of paper's blinkers to stop blinking.
It is illegal to type out on a pc ppr which is deactivated.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-activate-pc-ppr <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Cause blinkers to blink again.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-deactivate-pc-ppr-but-show-blinkers <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Cause all blinkers on this piece of paper to be stuck in the blunk (<font class="lisp">t</font>) state.
I.e. mark place but don't flash.  Deactivates so that they won't flash.
Typing out on this piece of paper will cause blinkers to start blinking again.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-return-pc-ppr <font class='italic' color='purple'>pc-ppr</font></font></font><br>
<font class="lisp">return-array</font> all of a piece of paper.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-make-stream <font class='italic' color='purple'>pc-ppr</font></font></font><br>
Returns a stream which accepts output and displays it on <font class="italic">pc-ppr</font>,
and reads input from the keyboard, echoing it on <font class="italic">pc-ppr</font>.
</div>

<div class='section'>4.12 The Keyboard</div>
Keyboard input can be done either by reading from the <font class="lisp">standard-input</font>
stream, which is preferred, or by calling these keyboard routines directly.

The characters read by the functions below are in the Lisp Machine
character set, with extra bits to incicate the Control and Meta
keys.  Also, the characters may come from the <font class="italic">forced-input</font>
mechanism (see (force-kbd-input-fun)), and may be from the mouse.
The byte fields which make up the fixnums returned by these functions
have names beginning with "<font class="lisp">%%kbd-</font>", and are explained on (%%kbd).

The special characters Break, Call, and Escape are normally intercepted
by the keyboard routines.  Break causes the process which reads it to
enter a <font class="lisp">break</font> loop (see (break-fun)).
Call returns control to the top-level job, or enters a <font class="lisp">break</font> loop
if control is already in the top-level job.  Control and Meta modifiers
cause additional effects.  See (call-key) for details.
Escape is a prefix for various commands, as in ITS.  Commands consist of
Escape, an optional numeric argument (in octal), and a letter, and do not echo.
The commands that currently exist are:
.table 1 500
.item &lt;esc&gt;C
Complement TV black-on-white mode.
.item &lt;esc&gt;<font class="italic">n</font>C
Complement black-on-white mode of plane <font class="italic">n</font>.
.item &lt;esc&gt;<font class="italic">n</font>S
Select video-switch input <font class="italic">n</font>.
.item &lt;esc&gt;M
Complement more-processing enable.
.item &lt;esc&gt;0M
Turn off more-processing.
.item &lt;esc&gt;1M
Turn on more-processing.
.end_table

<div class='defun'><font class='exdent'><font class='funcname'>kbd-tyi <font class='italic' color='purple'>&optional (whostate <font class="lisp">"TYI"</font>)</font></font></font><br>
This is the main routine for reading from the keyboard.
The optional argument is what to display as the program state in the
who line (usually just "TYI") while awaiting typein.  The value returned
is a number which consists of a Lisp machine character code, 
augmented with bits for the control and meta keys.
The character is not echoed.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>kbd-tyi-no-hang
Returns <font class="lisp"><font class='italic' color='purple'>nil</font> if no character has been typed, or the character</font></font></font><br>
code as <font class="lisp">kbd-tyi</font> would return it.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>kbd-char-available
Returns <font class='italic' color='purple'>non-<font class="lisp">nil</font> if there is a character waiting to be read; otherwise</font></font></font><br>
returns <font class="lisp">nil</font>.  It does not read the character out.  This function can
be used with <font class="lisp">process-wait</font>.
</div>

.defvar kbd-super-image-p
If the value of <font class="lisp">kbd-super-image-p</font> is non-<font class="lisp">nil</font>, checking for
the special characters Break, Call, and Escape is disabled.  Note that
you cannot lambda-bind this variable, because it is looked at in different
stack-groups.
.end_defvar

.defvar kbd-simulated-clock-fcn-list
List of functions to be called every 60th of a second (while the
machine is waiting for typein.)  This is used to implement blinkers.
[This variable should be renamed and moved to the scheduler section.]
.end_defvar

<div class='defun'><font class='exdent'><font class='funcname'>force-kbd-input <font class='italic' color='purple'>job input</font></font></font><br>
This is used to make a job think it has keyboard input that was not
actually typed by the user.  The menu system, for example, uses this.
<font class="italic">job</font> is the job to receive the input.  <font class="italic">input</font> is either a fixnum,
representing a single character, or an array of characters (which may or
may not be a string).  <font class="lisp">force-kbd-input</font> waits until previous
forced input has been read, then gives the new forced input to the job.
</div>

<div class='section'>4.13 Internal Special Variables</div>
.defvar tv-blinker-list
This is a list of all blinkers which are visible (blinking or
solidly on).  It is used by the <font class="lisp">tv-blinker-clock</font> routine
and by <font class="lisp">tv-open-screen</font>.
.end_defvar

.defvar tv-roving-blinker-list
This is a list of peculiar blinkers which don't stay on any single
piece of paper.  Whenever any piece of paper is opened, in addition
to that piece of paper's own blinkers, all of the roving blinkers
will be temporarily turned off.  Only the visible ones are on this list.
This is primarily for the mouse's blinker.
.end_defvar

.defvar tv-pc-ppr-list
This is a list of all the pieces of paper.
Currently for no particular reason.
.end_defvar

.defvar tv-white-on-black-state
[??]
.end_defvar

.defvar tv-beep-duration
Controls beeping.
.end_defvar

.defvar tv-beep-wavelength
Controls beeping.
.end_defvar

.defvar tv-more-processing-global-enable
This flag controls whether "**MORE**"'s can happen.  Complemented
by &lt;esc&gt;M.  The initial value is <font class="lisp">t</font>.
.end_defvar

<div class='section'>4.14 Font Utility Routines</div>
[Are these the latest word?  I suspect not.]

<div class='defun'><font class='exdent'><font class='funcname'>tv-get-font-pixel <font class='italic' color='purple'>font char row col</font></font></font><br>
Returns a number which is the pixel value of the specified
point in the specified character in the specified font.  This is
0 or 1 for normal fonts, or a gray-level value for multi-plane
fonts.  The value returned is zero if you address outside
of the character raster.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-store-font-pixel <font class='italic' color='purple'>pixel font char row col</font></font></font><br>
This is similar to the above, but stores.  It is an error to store
outside of the character raster.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-make-sideways-font <font class='italic' color='purple'>font</font></font></font><br>
Returns a new font which is the same, except turned on its side
in such a way that it works on pieces of paper created with
the <font class="lisp">sideways-p</font> <font class="lisp">t</font> option.
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-make-dbl-hor-font <font class='italic' color='purple'>font</font></font></font><br>
Returns a new font with alternating bits split into two planes
in such a way that it will work with doubled horizontal resolution
(producing squished characters if the original font had a normal
aspect ratio.)
</div>

<div class='defun'><font class='exdent'><font class='funcname'>tv-make-gray-font <font class='italic' color='purple'>font1 &optional (x-ratio 2) (y-ratio 2) (n-planes 2)</font></font></font><br>
Returns a new font which is the original font with areas
<font class="italic">x-ratio</font> wide and <font class="italic">y-ratio</font> high converted into single points
with an appropriate gray level value.  <font class="italic">n-planes</font> determines
the number of gray levels available.
</div>

<div class='section'>4.15 The Font Compiler</div><p class='cindent'><!-- font compiler -->

The Font Compiler is a lisp program which runs on the pdp10.
It converts fonts represented as AST files into QFASL files
which can be loaded into the Lisp machine.  When a font is loaded,
a symbol in the <font class="lisp">fonts</font> package is <font class="lisp">setq</font>'ed to
the representation of that font.

To run the font compiler, incant
<pre class="lisp">
:lispm1;qcmp
(fasload (lmio)fcmp)
(crunit dsk lmfont)  ;Or whatever directory you keep fonts on
(fcmp-1 '<font class="italic">input</font> '<font class="italic">output</font> '<font class="italic">fontname</font> <font class="italic">screen-type</font>)
</pre>

<font class="italic">input</font> is the first-name of the AST file containing the font
to be processed.  <font class="italic">output</font> is the first-name of the QFASL file
to be produced.  <font class="italic">fontname</font> is the name of the symbol in the
<font class="lisp">fonts</font> package whose value will be the font.  This symbol will
also appear in the <font class="lisp">font-name</font> field of the font and in the printed
representation of the font.
<font class="italic">screen-type</font> is <font class="lisp">t</font> if the font is to be used with the 32-bit
TV controller, or <font class="lisp">nil</font> if the font is to be used with the 16-bit controller.

[Here insert a catalog of fonts when things settle down a little more.]

.eof
</body>
</html>

